

    \filetitle{figure}{Start new figure}{report/figure}

	\paragraph{Syntax}

\begin{verbatim}
P.figure(Caption,...)
\end{verbatim}

\paragraph{Syntax to capture an existing figure
window}

This is an obsolete syntax, and will be removed from IRIS in a future
release. Use \href{report/userfigure}{\texttt{report/userfigure}}
instead.

\begin{verbatim}
P.figure(Caption,H,...)
\end{verbatim}

\paragraph{Input arguments}

\begin{itemize}
\item
  \texttt{P} {[} struct {]} - Report object created by the
  \href{report/new}{\texttt{report.new}} function.
\item
  \texttt{Caption} {[} char \textbar{} cellstr {]} - Title or a cell
  array with title and subtitle displayed at the top of the figure; see
  Description for splitting the title or subtitle into multiple lines.
\item
  \texttt{H} {[} numeric {]} - See help on
  \href{report/userfigure}{\texttt{report/userfigure}}.
\end{itemize}

\paragraph{Options}

\begin{itemize}
\item
  \texttt{\textquotesingle{}aspectRatio=\textquotesingle{}} {[}
  \texttt{@auto} \textbar{} numeric {]} - Plot box aspect ratio for all
  graphs in the figure; must be a 1-by-2 vector describing the
  horizontal-to-vertical ratio.
\item
  \texttt{\textquotesingle{}captionTypeface=\textquotesingle{}} {[}
  cellstr \textbar{} char \textbar{}
  \emph{\texttt{\textquotesingle{}\textbackslash{}large\textbackslash{}bfseries\textquotesingle{}}}
  {]} - LaTeX format commands for typesetting the figure caption; the
  subcaption format can be entered as the second cell in a cell array.
\item
  \texttt{\textquotesingle{}close=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - (Inheritable from
  parent objects) Close the underlying figure window when finished; see
  Description.
\item
  \texttt{\textquotesingle{}separator=\textquotesingle{}} {[} char
  \textbar{}
  \emph{\texttt{\textquotesingle{}\textbackslash{}medskip\textbackslash{}par\textquotesingle{}}}
  {]} - (Inheritable from parent objects) LaTeX commands that will be
  inserted after the figure.
\item
  \texttt{\textquotesingle{}figureOpt=\textquotesingle{}} {[} cell
  \textbar{} \emph{empty} {]} - Figure options that will be applied to
  the figure handle at opening.
\item
  \texttt{\textquotesingle{}figureScale=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{0.85}} {]} - (Inheritable from parent
  objects) Scale of the figure in the LaTeX document.
\item
  \texttt{\textquotesingle{}figureTrim=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{0}} {]} - Trim figure when it is inserted
  into the report by the specified amount of points; must be either a
  scalar or a 1-by-4 vector (points removed from left, bottom, right,
  top).
\item
  \texttt{\textquotesingle{}footnote=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - Footnote at the figure title; only shows
  if the title is non-empty.
\item
  \texttt{\textquotesingle{}sideways=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - (Inheritable from
  parent objects) Print the table rotated by 90 degrees.
\item
  \texttt{\textquotesingle{}style=\textquotesingle{}} {[} struct
  \textbar{} \emph{empty} {]} - Apply this cascading style structure to
  the figure; see \href{grfun/style}{\texttt{grfun.style}}.
\item
  \texttt{\textquotesingle{}subplot=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{\textquotesingle{}auto\textquotesingle{}}}
  {]} - (Inheritable from parent objects) Subplot division of the
  figure.
\item
  \texttt{\textquotesingle{}typeface=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - (Not inheritable from parent objects)
  LaTeX code specifying the typeface for the figure as a whole; it must
  use the declarative forms (such as \texttt{\textbackslash{}itshape})
  and not the command forms (such as
  \texttt{\textbackslash{}textit\{...\}}).
\item
  \texttt{\textquotesingle{}visible=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - (Inheritable from
  parent objects) Visibility of the underlying Matlab figure window.
\end{itemize}

\paragraph{Generic options}

See help on \href{report/Contents}{generic options} in report objects.

\paragraph{Description}

Figures are top-level report objects and cannot be nested within other
report objects, except \href{report/align}{\texttt{align}}. Figure
objects can have the following types of children:

\begin{itemize}
\tightlist
\item
  \href{report/graph}{\texttt{graph}};
\item
  \href{report/empty}{\texttt{empty}}.
\end{itemize}

\subparagraph{Titles and subtitles}

The input argument \texttt{Caption} can be either a text string, or a
1-by-2 cell array of strings. In the latter case, the first cell will be
printed as a title, and the second cell will be printed as a subtitle.

To split the title or subtitle into multiple lines, use the following
LaTeX commands wrapped in curly brackets:
\texttt{\{\textbackslash{}\textbackslash{}\}} or
\texttt{\{\textbackslash{}\textbackslash{}{[}Xpt{]}\}}, where \texttt{X}
is the width of an extra vertical space (in points) added between the
respective lines.

\subparagraph{Figure handle}

If the option \texttt{\textquotesingle{}close=\textquotesingle{}} is set
to \texttt{false} the figure window will remain open after the report is
published. The handle to this figure window will be included in the
field \texttt{.figureHandle} of the information struct \texttt{Info}
returned by \href{report/publish}{\texttt{report/publish}}.

\paragraph{Example}


